<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.11"/>
<title>Kinetis Bootloader: Memory Interface</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
  $(document).ready(function() { init_search(); });
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td id="projectlogo"><img alt="Logo" src="nxp_logo_small.png"/></td>
  <td id="projectalign" style="padding-left: 0.5em;">
   <div id="projectname">Kinetis Bootloader
   &#160;<span id="projectnumber">2.0.0</span>
   </div>
   <div id="projectbrief">Common bootloader for Kinetis devices</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.11 -->
<script type="text/javascript">
var searchBox = new SearchBox("searchBox", "search",false,'Search');
</script>
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>Introduction</span></a></li>
      <li class="current"><a href="pages.html"><span>Related&#160;Pages</span></a></li>
      <li><a href="modules.html"><span>Modules</span></a></li>
      <li>
        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <img id="MSearchSelect" src="search/mag_sel.png"
               onmouseover="return searchBox.OnSearchSelectShow()"
               onmouseout="return searchBox.OnSearchSelectHide()"
               alt=""/>
          <input type="text" id="MSearchField" value="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
          </span>
        </div>
      </li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('memifpage.html','');});
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div class="header">
  <div class="headertitle">
<div class="title">Memory Interface </div>  </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><h1>Abstract interface</h1>
<p>The bootloader uses a common, abstract interface to implement the memory read/write/fill commands. This is to keep the command layer from having to know the details of the memory map and special routines. This memory interface is documented in detail <a class="el" href="group__memif.html">here</a>.</p>
<p>A shared <code><a class="el" href="group__memif.html#structmemory__interface__t" title="Interface to memory operations. ">memory_interface_t</a></code> struct is used for both the high-level abstract interface, as well as low-level entries in the memory map.</p>
<p>The global bootloader context contains a pointer to the high-level abstract memory interface, which is one of these <code><a class="el" href="group__memif.html#structmemory__interface__t" title="Interface to memory operations. ">memory_interface_t</a></code> structs. The internal implementation of this abstract interface uses a memory map table, referenced from the global bootloader context, that describes the various regions of memory that are accessible and provides region-specific operations.</p>
<p>The high-level functions are implemented to iterate over the memory map entries until it finds the entry for the specified address range. Read and write operations are not permitted to cross region boundaries, and an error will be returned if such an attempt is made.</p>
<p>The <code><a class="el" href="group__context.html#a2f6fd28824e65401a365bd7066cd5ee0" title="Memory map used by abstract memory interface. ">bootloader_context_t::memoryMap</a></code> member is set to an array of the <code><a class="el" href="group__memif.html#structmemory__map__entry__t" title="Structure of a memory map entry. ">memory_map_entry_t</a></code> structures. This array must be terminated with an entry with all fields set to zero. The same <code><a class="el" href="group__memif.html#structmemory__interface__t" title="Interface to memory operations. ">memory_interface_t</a></code> struct is also used to hold the memory-type-specific operations.</p>
<p>Note that the <code>memory_map_entry_t::endAddress</code> field must be set to the address of the last byte of the region, because a &lt;= comparison is used.</p>
<p>Here is an example memory map:</p>
<div class="fragment"><div class="line"><a class="code" href="group__memif.html#structmemory__map__entry__t">memory_map_entry_t</a> <a class="code" href="group__memif.html#ga0cc5deda096db2c6f7022ae58c8e594f">g_memoryMap</a>[] = {</div><div class="line">    {0x00000000, 0x0001ffff, <a class="code" href="group__memif.html#ggaac34dfe6c6b73b43a4656c9dce041034acf4fb7fb9c61d4222ec903de4e194f1a">kMemoryIsExecutable</a>, &amp;<a class="code" href="group__memif.html#ga42219a1c0426b6b8406403e902aa9f9c">g_flashMemoryInterface</a>},   <span class="comment">// Flash array (128KB)</span></div><div class="line">    {0x1fffe000, 0x20003fff, <a class="code" href="group__memif.html#ggaac34dfe6c6b73b43a4656c9dce041034acf4fb7fb9c61d4222ec903de4e194f1a">kMemoryIsExecutable</a>, &amp;<a class="code" href="group__memif.html#ga1ac8541173ea5f76c889048abfaed8c5">g_normalMemoryInterface</a>},  <span class="comment">// SRAM (24KB)</span></div><div class="line">    {0x40000000, 0x4007ffff, <a class="code" href="group__memif.html#ggaac34dfe6c6b73b43a4656c9dce041034af06df00d223a4972f78ba2ed3282296c">kMemoryNotExecutable</a>, &amp;<a class="code" href="group__memif.html#ga6d612913b0600fd3f8fc0b5e6683df4a">g_deviceMemoryInterface</a>}, <span class="comment">// AIPS peripherals</span></div><div class="line">    {0x400ff000, 0x400fffff, <a class="code" href="group__memif.html#ggaac34dfe6c6b73b43a4656c9dce041034af06df00d223a4972f78ba2ed3282296c">kMemoryNotExecutable</a>, &amp;g_deviceMemoryInterface}, <span class="comment">// GPIO</span></div><div class="line">    {0xe0000000, 0xe00fffff, <a class="code" href="group__memif.html#ggaac34dfe6c6b73b43a4656c9dce041034af06df00d223a4972f78ba2ed3282296c">kMemoryNotExecutable</a>, &amp;g_deviceMemoryInterface}, <span class="comment">// M4 private peripherals</span></div><div class="line">    {0}                                                                       <span class="comment">// Terminator</span></div><div class="line">};</div></div><!-- fragment --><p>During bootloader startup, the memory map is copied into RAM and modified to match the actual sizes of flash and RAM on the chip, as determined by reading the <code>SIM_SDID</code> and <code>SIM_FCFG1/2</code> registers.</p>
<h1>Flash Driver Interface</h1>
<p>The flash driver uses the common memory interface listed above to simplify the interaction with flash. It also takes care of high level features such as readback verification, flash protection awareness, and so on. The flash memory functions map to the interface functions as so:</p>
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code" href="group__memif.html#structmemory__region__interface__t">memory_region_interface_t</a> <a class="code" href="group__memif.html#ga42219a1c0426b6b8406403e902aa9f9c">g_flashMemoryInterface</a> = {</div><div class="line">    .init = &amp;flash_mem_init,</div><div class="line">    .read = &amp;flash_mem_read,</div><div class="line">    .write = &amp;flash_mem_write,</div><div class="line">    .fill = &amp;flash_mem_fill,</div><div class="line">    .flush = flash_mem_flush,</div><div class="line">    .erase = <a class="code" href="group__memif.html#ga4c6b555730dd1b726ec6cec5ae260639">flash_mem_erase</a>,</div><div class="line">};</div></div><!-- fragment --><table class="doxtable">
<tr>
<th>API </th><th>Description  </th></tr>
<tr>
<td><code>flash_mem_init()</code> </td><td>Updates the flash memory map. </td></tr>
<tr>
<td><code>flash_mem_read()</code> </td><td>Performs a normal memory read after verify access. </td></tr>
<tr>
<td><code>flash_mem_write()</code> </td><td>Calls the low-level <code>flash_program()</code> API. Also performs program verification if enabled with the Set Property command. </td></tr>
<tr>
<td><code>flash_mem_fill()</code> </td><td>Performs intelligent fill operations on flash memory ranges. If the fill pattern are all 1's then special action is taken. If the range is a whole number of sectors, then those sectors are erased rather than filled. Any part of an all-1's fill that is not sector-aligned and -sized is ignored (the assumption being that it has been erased to 1's already). Fills for patterns other than all 1's call into <code>flash_program()</code>. </td></tr>
<tr>
<td><code>flash_mem_flush()</code> </td><td>Writes final flash sector, padded with 0xFFs. </td></tr>
<tr>
<td><code><a class="el" href="group__memif.html#ga4c6b555730dd1b726ec6cec5ae260639" title="Erase Flash memory. ">flash_mem_erase()</a></code> </td><td>Calls the low-level <code>flash_erase()</code> API. Also performs program verification if enabled with the Set Property command. </td></tr>
</table>
<p>All routines check the flash protection status for the sectors being programmed or erased and return an appropriate error if the operation is not allowed.</p>
<p>Bootloader startup code is responsible for initializing the flash memory controller.</p>
<h1>Low level flash driver</h1>
<p>The low level flash driver (LLFD) handles erase and write operations on a word basis. It cannot perform writes of less than a full word.</p>
<p>Bootloader startup code is responsible for initializing and shutting down the LLFD.</p>
<div class="fragment"><div class="line"><span class="keyword">typedef</span> <span class="keyword">struct </span>FlashDriverInterface</div><div class="line">{</div><div class="line">    <a class="code" href="group__bl__core.html#unionstandard__version__t">standard_version_t</a> version; </div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_init)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_erase_all)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t key);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_erase_all_unsecure)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t key);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_erase)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t start, uint32_t lengthInBytes, uint32_t key);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_program)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_get_security_state)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <a class="code" href="group__flash__driver.html#ga00b3eb2666116e617f6e45a10218f6a9">flash_security_state_t</a> *state);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_security_bypass)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <span class="keyword">const</span> uint8_t *backdoorKey);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_verify_erase_all)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <a class="code" href="group__flash__driver.html#ga2105f5de393a06479e62141dab8dd3fc">flash_margin_value_t</a> margin);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_verify_erase)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config,</div><div class="line">                                   uint32_t start,</div><div class="line">                                   uint32_t lengthInBytes,</div><div class="line">                                   <a class="code" href="group__flash__driver.html#ga2105f5de393a06479e62141dab8dd3fc">flash_margin_value_t</a> margin);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_verify_program)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config,</div><div class="line">                                     uint32_t start,</div><div class="line">                                     uint32_t lengthInBytes,</div><div class="line">                                     <span class="keyword">const</span> uint32_t *expectedData,</div><div class="line">                                     <a class="code" href="group__flash__driver.html#ga2105f5de393a06479e62141dab8dd3fc">flash_margin_value_t</a> margin,</div><div class="line">                                     uint32_t *failedAddress,</div><div class="line">                                     uint32_t *failedData);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_get_property)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <a class="code" href="group__flash__driver.html#ga7b6766fe08a63cf92a5e2a90dd6d010f">flash_property_tag_t</a> whichProperty, uint32_t *value);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_register_callback)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <a class="code" href="group__flash__driver.html#ga67c22466713ef09903b07a56e1c2a050">flash_callback_t</a> callback);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_program_once)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t index, uint32_t *src, uint32_t lengthInBytes);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_read_once)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t index, uint32_t *dst, uint32_t lengthInBytes);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_read_resource)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config,</div><div class="line">                                    uint32_t start,</div><div class="line">                                    uint32_t *dst,</div><div class="line">                                    uint32_t lengthInBytes,</div><div class="line">                                    <a class="code" href="group__flash__driver.html#ga70d45ebc64d50e9868f7016c8a417c51">flash_read_resource_option_t</a> option);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_prepare_execute_in_ram_functions)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_is_execute_only)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config,</div><div class="line">                                      uint32_t start,</div><div class="line">                                      uint32_t lengthInBytes,</div><div class="line">                                      <a class="code" href="group__flash__driver.html#gad38961e5692f64548dbf84d652b9ccde">flash_execute_only_access_state_t</a> *access_state);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_set_flexram_function)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, <a class="code" href="group__flash__driver.html#ga3812bab3ef6aacfbe889b1a81e25c76d">flash_flexram_function_option_t</a> option);</div><div class="line">    <a class="code" href="group__ksdk__common.html#gaaabdaf7ee58ca7269bd4bf24efcde092">status_t</a> (*flash_program_section)(<a class="code" href="group__flash__driver.html#structflash__config__t">flash_config_t</a> *config, uint32_t start, uint32_t *src, uint32_t lengthInBytes);</div><div class="line">} <a class="code" href="group__context.html#structflash__driver__interface__t">flash_driver_interface_t</a>;</div></div><!-- fragment --><p>The Flash Driver API can be called from an external application. For further information see the Flash Driver API example in <code>apps/flash_driver_api</code>. </p>
</div></div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Mon Mar 7 2016 16:48:23 for Kinetis Bootloader by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.11 </li>
  </ul>
</div>
</body>
</html>
